Subprimitivcs 200 Lisp Machine Manual 



14. Siibpriniitives 



Subprimitivcs arc functions whicii arc not intended to be used by the average program, only 
by "system programs", 'l^hcy allow one to manipulate tlic environment at a level lower than 
normal Lisp. 1licy are described in tliis chapter. Subprimitivcs usually have names starting with 
a % character. The "primitives" described in other sections of the manual typically use 
subprimitivcs to accomplish tlieir work. To some extent the subprimitivcs take tlic place of what 
in other systems would be individual machine instructions. Subprimitivcs are normally hand-coded 
in microcode. 

1"here is plenty of stuif in this chapter that is not flilly explained; there arc terms that are 
undefined, tlicrc arc forward references, and so on. Furthermore, most of what is in here is 
considered subject to change without notice. In fact, this chapter docs not exactly belong in this 
manual, but in some other more low-level manual. Since the latter manual does not exist, it is 
here for the interim. 

Subprimitivcs by their very nature cannot do full checking. Improper use of subprimitivcs can 
destroy the environment. Subprimitivcs come in varying degrees of dangcrousncss. 'Lhose without 
a % sign in their name cannot destroy tlie environment, but are dependent on "internal" details 
of the Lisp implementation. ITie ones whose names start with a % sign can violate system 
conventions if used improperly. The subprimitivcs are documented here since they need to be 
documented somewhere, but this manual does not document all the things you need to know in 
order to use them. Still other subprimitivcs are not dcKumented here because they are very 
specialized. Most of tliese are never used explicitly by a programmer; tlie compiler inserts them 
into the program to perform operations which are expressed differently in the source code. 

The most common problem you can cause using subprimitivcs, though by no means the only 
one, is to create illegal pointers: pointers that are, for one reason or another, according to 
storage conventions, not allowed to exist. The storage conventions are not documented; as we 
said, you have to be an expert to use a lot of the functions in this chapter correctly. If you 
create such an illegal pointer, it probably will not be detected immediately, but later on parts of 
the system may see it, notice that it is illegal, and (probably) halt tlie Lisp Machine. 

In a certain sense car, cdr, rplaca, and rplacd are subprimitivcs. If these are given a 
locative instead of a list, they will access or modify the cell addressed by tlie locative without 
regard to what object the cell is inside. Subprimitivcs can be used to create locatives to strange 
places. 
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Datatypes 



14.1 Data Types 

data-type arg 

data-type returns a symbol that is the name for tlic internal data-type of tlic "pointer" 
that represents arg. Note that some types as seen by the user arc not distinf'uishcd from 
each other at this level, and some user types may be represented by more than one 
internal type. For example, dtp-extended -number is tlie symbol that data-type would 
return for either a flonum or a bignum, even tliough tliose two types are quite different. 
The typep function (page 11) is a higher-level primitive tliat is more useful in most cases; 
normal programs should always use typep rather than data-type. Some of these type 
codes are internal tag fields that are never used in pointers that represent Lisp objects at 
all, but tliey are documented here anyway. 



dtp-symbol 
dtp-fix 

dtp-small-flonum 



'ITie object is a symbol 

The object is a fixnum; tlic numeric value is contained in the 
address field of the pointer. 



ITie object is a small flonum; tlie numeric value is contained in 
the address field of the pointer. 

dtp-extended-number The object is a flonum or a bignum. This value will also be 

used for future numeric types. 

The object is a cons. 

The object is a locative pointer. 

The object is an array. 

The object is a compiled fianction. 

7Tie object is a microcode entry. 

The object is a closure; see chapter 11, page 180. 

The object is a stack-group; see chapter 12, page 186. 

The object is an instance of a flavor; see chapter 20, page 321. 

The object is an entity; see section 11.4, page 185. 

The object is a "select-method"; see page 163. 

An internal type used to mark the first word of a multi-word 
structure. 

An internal type used to mark the first word of an array. 

An internal type used to mark the first word of a symbol. 

An internal tvne used to mark the first word of an instance- 



dtp -list 

dtp -locative 

dtp -array -pointer 

dtp-fef-pointer 

dtp -u -entry 

dtp-closure 

dtp-stack-group 

dtp- instance 

dtp -entity 

dtp -select -method 

dtp -header 



dtp -array -header 
dtp -symbol -header 
dtp - instance- header 
dtp- null 



dtp-trap 



Nothing to do with nil. This is used in unbound value and 
ftinction cells. An attempt to refer to the contents of a cell that 
contains a dtp -null gets an error. This is how "unbound 
variable" and "undefined function" errors are detected. 

The zero data-type, which is not used, lliis hopes to detect 
microcode bugs. 
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dtp -free ITiis type is used to fill free storage, to catch wild references. 

dtp-external -value-cell -pointer 

An "invisible pointer" used for external value cells, which are 
part of ihe closure mechanism (see chapter 11, page 180), and 
used by compiled code to address value and function cells. 

dtp -header -forward An "invisible pointer" used to indicate that the structure 

containing it has been moved elsewhere. The "header word" of 
the structure is replaced by one of these invisible pointers. See 
the fijnciion structure -forward (page 203). 

dtp-body-forward An "invisible pointer" used to indicate that the structure 

containing it has been moved elsewhere. I'his points to the word 
containing the header- forward, which points to the new copy of 
the structure. 

dtp - one -q -forward An "invisible pointer" used to indicate that the single cell 

containing it has been moved elsewhere. 

dtp -gc- forward This is used by the copying garbage collector to flag the obsolete 

copy of an object; it points to the new copy. 

q-data-types Variable 

llie value of q-data-types is a list of all of the symbolic names for data types described 
above under data -type. Ihese are the symbols whose print names begin with "dtp-". 
The values of these symbols are the internal numeric data-type codes for the various types. 

q-data-types type-code 

Given the internal numeric data-type code, returns the corresponding symbolic name. 
This "function" is actually an array. 

14.2 Forwarding 

An invisible pointer is a kind of pointer that does not represent a Lisp object, but just resides 
in memory. Fhere are several kinds of invisible pointer, and there are various rules about where 
they may or may not appear. ITie basic property of an invisible pointer is that if the Lisp 
Machine reads a word of memory and finds an invisible pointer there, instead of seeing the 
invisible pointer as the result of the read, it does a second read, at the location addressed by the 
invisible pointer, and returns that as the result instead. Writing behaves in a similar fashion. 
When the Lisp Machine writes a word of memory it first checks to see if that word contains an 
invisible pointer; if so it goes to the location pointed to by the invisible pointer and tries to write 
there instead. Many subprimitives that read and write memory do not do this checking. 

The simplest kind of invisible pointer has the data type code dtp -one -q -forward. It is used 
to forward a single word of memory to someplace else. ITie invisible pointers with data types 
dtp -header -forward and dtp -body -forward are used for moving whole Lisp objects (such as 
cons cells or arrays) somewhere else. Ilie dtp-external-value-cell-polnter is very similar to the 
dtp-one-q-forward; the difference is that it is not "invisible" to the operation of binding. If the 
(internal) value cell of a symbol contains a dtp -external -value -cell -pointer that points to some 
other word (the external value cell), then symeval or set operations on the symbol will consider 
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the pointer to be invisible and use the external value cell, but binding the symbol will save away 
the dtp-externai-vaiue-ceii -pointer itself, and store the new value into the internal value cell of 
tlie symbol. This is how closures are implemented. 

dtp-gc-foPyA/ard is not an invisible pointer at all; it only appears in "old space" and will 
never be seen by any program other dian die garbage collector. When an object is found not to 
be garbage, and die garbage collector moves it from "old space" to "new space", a dtp-gc- 
forward is left behind to point to the new copy of the object, ihis ensures Uiat other references 
to die same object get the same new copy. 

structure-forward old-object newobjeci 

This causes references to old- object actually to reference new-object, by storing invisible 
pointers in old-object. It returns old-object. 

An example of die use of structure- forward is adjust-array-size. If the array is being 
made bigger and cannot be expanded in place, a new array is allocated, die contents are 
copied, and die old array is structure-forwarded to die new one. lliis forwarding ensures 
dial pointers to die old array, or to cells within it, continue to work. When die garbage 
collector goes to copy die old array, it notices die forwarding and uses die new array as 
die copy; dius die overhead of forwarding disappears eventually if garbage collection is in 
use. 

follow-structure-forwarding object 

Normally returns object, but if object has been structure -forward'ed, returns die object 
at die end of die chain of forwardings. If object is not exacdy an object, but a locative 
to a cell in die middle of an object, a locative to die corresponding cell in die latest copy 
of die object will be returned. 

forward-value-cell from-symbol to-symbol 

This alters from-symbol so diat it always has die same value as to-symbol by sharing its 
value cell. A dtp-one-q -forward invisible pointer is stored into from-symboFs value cell. 
Do not do diis while from-symbol is lambda-bound, as die microcode does not bodier to 
check for diat case and something bad will happen when from-symbol gets unbound. The 
microcode check is omitted to speed up binding and unbinding. 

To forward one arbitrary cell to another (rather dian specifically one value cell to 
another), given two locadves, do 

(7op-store-tag-and-pointer locativel dtp-one-q-forward locative!) 

fol low-cell -forwarding he evcp-p 

loc is a locadve to a cell. Normally he is returned, but if die cell has been forwarded, 
diis follows die chain of forwardings and returns a locative to die final cell. If die cell is 
part of a structure which has been forwarded, die chain of structure fonvardings is 
followed, too. If evcp-p is t, external value cell pointers arc followed; if it is nil diey are 
noL 
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14.3 Pointer Manipulation 

It should again be emphasized that improper use of these functions can damage or destroy the 
Lisp environment, h is possible to create pointers with illegal data-type, pointers to non-existent 
objects, and pointers to untyped storage, which will completely confuse the garbage collector. 

%data-type x 

Returns the data-type field of x, as a fixnum. 

%pointep X 

Returns the pointer field of a. as a fixnum. For most types, this is dangerous since the 
garbage collector can copy tlic object and change its address. 

%malce-pointer data- type pointer 

This makes up a pointer, with data-type in tlie data-type field and pointer in the pointer 
field, and returns it. data-type should be an internal numeric data-type code; these are 
the values of the symbols tliat start with dtp-, pointer may be any object; its pointer 
field is used. This is most commonly used for changing the type of a pointer. Do not 
use this to make pointers which are not allowed to be in the machine, such as dtp- null, 
invisible pointers, etc. 

%make-pointer-offset data-type pointer offset 

This returns a pointer with data-type in the data-type field, and pointer plus offset in the 
pointer field. The data- type and pointer arguments are like those of %make- pointer; 
offset may be any object but is usually a fixnum. The types of the arguments are not 
checked; their pointer fields are simply added together. This is useful for constructing 
locative pointers into the middle of an object. However, note that it is illegal to have a 
pointer to untyped data, such as the inside of a FEF or a numeric array. 

%po inter-difference pointer-1 pointer^! 

Returns a fixnum which is pointer-I minus pointer-2. No type checks are made. For the 
result to be meaningful, the two pointers must point into the same object, so that their 
diflxjrence cannot change as a result of garbage collection. 

14.4 Analyzing Structures 

%f ind-structure-header pointer 

This subprimitive finds the structure into which pointer points, by searching backward for 
a header. It is a basic low-level function used by such diings as the garbage collector. 
pointer is normally a locative, but its data-type is ignored. Note tiiat it is illegal to point 
into an "unboxed" portion of a structure, for instance the middle of a numeric array. 

In structure space, the "containing structure" of a pointer is well-defined by system 
storage conventions. In list space, it is considered to be the contiguous, cdr-coded 
segment of list surrounding the location pointed to. If a cons of the list has been copied 
out by rplacd, die contiguous list includes that pair and ends at that point. 
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%find- structure- leader pointer 

riiis is identical to %find -structure- header, except that if the structure is an array witu 
a leader, this returns a locative pointer to tJie leader-header, rather than returning the 
array-pointer itself. Thus the result of %find- structure -leader is always the lowest 
address in tlie structure. This is the one used internally by the garbage collector. 

%structure-boxed-siz9 object 

Returns tlie number of "boxed Q's" in object. This is the number of words at the front 
of tlie structure which contain nornial Lisp objects. Some structures, for example FBFs 
and numeric arrays, contain additional "unboxed Q's" following their "boxed Q's". Note 
that the boxed size of a PDL (either regular or special) does not include Q's above the 
current top of tlie PDL. Those locations are boxed, but their contents are considered 
garbage and are not protected by the garbage collector. 

%structure-total-size object 

Returns the total number of words occupied by the representation of object, including 
boxed Q's, unboxed Q's, and garbage Q's off the ends of PDLs. 

14.5 Creating Objects 

%anocate-and-initialize data-type header-type header second-word area size 

This is the subprimitive for creating most structured-type objects, area is the area in 
which it is to be created, as a fixnum or a symbol, size is the number of words to be 
allocated. The value returned points to the first word alkxrated and has data-type data- 
type. Unintermptibly, the words allocated are initialized so diat storage conventions are 
preserved at all times. ITie first word, the header, is initialized to have header-type in its 
data-type field and header in its pointer field, llie second word is initialized to second- 
word. The remaining words are initialized to nil. ITie flag bits of all words are set to 0. 
The cdr codes of all words except the last are set to cdr-next; the cdr code of the last 
word is set to cdr-nil. It is probably a bad idea to rely on this. 

The basic functions for creating list- type objects are cons and make -list; no special 
subprimitive is needed. Closures, enuties, and select-methods are based on lists, but there is no 
primitive for creating them. To create one, create a list and then use %make- pointer to change 
the data type from dtp -list to the desired type. 

%anocate-and-initia1ize-arpay header data-length leader-length area size 

This is die subprimitive for creating arrays, called only by make -array. It is different 
from %allocate- and -initialize because arrays have a more complicated header structure. 
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14.6 Copying Data 

%blt from to count increment 

Copies count words, separated by increment. The word at address from is moved to 
address to, the word at address from + increment is moved to address to + increment, and 
so on until count words have been moved. 

%blt is useful for copying parts of structures, making or deleting space inside structures, 
and initializing structures. 

Only tJie pointer fields of from and to are significant; they may be locatives or even 
fixnums. If one of tliem must point to the unboxed data in the middle of a structure, 
you must make it a fixnum, and you must do so with interrupts disabled, or else garbage 
collection could move the structure after you have already created the fixnum. 

14.7 Returning Storage 

return-storage object 

ITiis peculiar function attempts to return object to free storage. If it is a displaced array, 
this returns the displaced array itself, not the data that the array points to. Currently 
return -storage docs nothing if the object is not at the end of its region, i.e. if it was not 
either the most recently allocated non-list object in its area, or tlic most recently allocated 
list in its area. 

If you still have any references to object anywhere in the Lisp world after this ftjnction 
returns, die garbage collector can get a fatal error if it sees them. Since the form that 
calls this function must get the object from somewhere, it may not be clear how to legally 
call return -storage. One of the only ways to do it is as follows: 
(defun func () 

(let ({object (make-array 100))) 

(return-storage (progl object (setq object nil))))) 
so that the variable object does not refer to the object when return -storage is called. 
Alternatively, you can free the object and get rid of all pointers to it while interrupts are 
turned off with without -interrupts. 

You should only call this function if you know what you are doing; otherwise the garbage 
collector can get fatal errors. Be carefLil. 
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14.8 Locking Subprimitive 

%store-conclitional pointer old new 

This is the basic locking primitive, pointer is a locative to a cell which is unintcrruptibly 

n-au aiiu wiuLcii. u uic cuiiLciila «.;i uic cwii o cq U) utCi, UiCu ii is iCpidCcu uy //etv aiiu 

t is returned. Otherwise, nil is returned and the contents of the cell are not changed. 

14.9 I/O Device Subprimitives 

%uni bus- read address 

Returns as a fixnum the contents of the register at the specified Unibus address. You 
must specify a full 18-bit address. I'his is guaranteed to read the location only once. 
Since tlic Lisp Machine Unibus docs not support byte operations, this always references a 
16-bit word, and so address will normally be an even number. 

%uni bus -write address data 

Writes the 16-bit number data at tlie specified Unibus address, exactly once. 

%x bus-read io-ojfset 

Returns the contents of the register at the specified Xbus address, io-ojfset is an oifset 
into the 1/0 portion of Xbus physical address space. This is guaranteed to read the 
location exactly once. The returned value can be either a fixnum or a bignum. 

%xbus -write io-offset data 

Writes data., which can be a fixnum or a bignum, into the register at the specified Xbus 
address, io-ojfset is an ofi'set into the I/O portion of Xbus physical address space. This is 
guaranteed to write the location exactly once. 

sys:%xbus-write-sync w-loc w-data delay sync-Joe sync-mask sync-value 

Does (%xbus-write m-Zoc w-data), but first synchronizes to within about one microsecond 
of a certain condition. The synchronization is achieved by looping until 
(= (logand {%xbus-read sync-loc) sync-mask) sync-value) 
is false, then looping until it is true, tlien looping delay times. Thus the write happens a 
specified delay after the leading edge of the synchronization condition. The number of 
microseconds of delay is roughly one third of delay. 

sys:%ha1t 

Stops the machine. 
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14.10 Special Memory Referencing 

%p-contents-offset base-pointer ojfset 

This checks the cell pointed to by base-pointer for a forwarding pointer, }^aving followed 
forwarding pointers to die real structure pointed to, it adds ojfset to die resulting 
forwarded base-pointer and returns die contents of that location. 

There is no %p -contents, since car perfomis Uiat operation. 

%p -contents -as -locative pointer 

Given a pointer to a memory location containing a pointer diat isn't allowed to be "in die 
machine" (typically an invisible pointer) this function returns die contents of die location 
as a dtp -locative. It changes die disallowed data type to dtp -locative so diat you can 
safely look at it and see what it points to. 

%p-contents-as-locative-offset base-pointer offset 

This checks die cell pointed to by base-pointer for a forwarding pointer. Having followed 
forwarding pointers to die real staicture pointed to, it adds offset to die resuming 
forwarded base-pointer, fetches die contents of diat location, and returns it with die data 
type changed to dtp -locative in case it was a type diat isn't allowed to be "in die 
machine" (typically an invisible pointer). This can be used, for example, to analyze die 
dtp-external-value-cell-pointer pointers in a FEF, which are used by die compiled 
code to reference value cells and function cells of symbols. 

%p-store-contents pointer value 

value is stored into die data-type and pointer fields of die location addressed by pointer. 
The cdr-code and flag-bit fields remain unchanged, value is returned. 

%p-store-contents-offset value base-pointer offset 

This checks die cell pointed to by base-pointer for a forwarding pointer. Having followed 
forwarding pointers to the real structure pointed to, it adds offset to the resulUng 
forwarded base-pointer and stores value into the data-type and pointer fields of tiiat 
locadon. ITie cdr-code and flag-bit fields remain unchanged, value is returned. 

%p-store-tag-ancl-po1nter pointer miscfields pntrfield 

Creates a ^ by taking 8 bits from miscfields and 24 bits from pntrfield, and stores diat 
into die location addressed by pointer. The low 5 bits of miscfields become die data-type, 
die next bit becomes die flag-bit, and die top two bits become die cdr-code. This is a 
good way to store a forwarding pointer from one structure to anodier (for example). 

%p-ldb ppss pointer 

This is like Idb but gets a byte fi-om die location addressed by pointer. Note diat you 
can load bytes out of die data type etc. bits, not just die pointer field, and diat die word 
loaded out of need not be a fixnum. The result returned is always a fixnum. 
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%p-ldb-offs8t ppss base- pointer offset 

This checks the cell pointed to by base-pointer for a forwarding pointer. Having followed 
forwarding pointers to the real structure pointed to, the byte specified by ppss is loaded 
from the contents of the location addressed by the forwarded base-pointer plus offset, and 
returned as a fixnum. Iliis is Uie way to reference byte fields withui a structure without 
violating system storage conventions. 

%p-dpb value ppss pointer 

The value, a fixnum, is stored into the byte selected by ppss in tlic word addressed by 
pointer, nil is returned. You can use tliis to alter data types, cdr codes, etc. 

%p-dpb-offset value ppss base- pointer offset 

This checks the cell pointed to by base-pointer for a forwarding pointer. Having followed 
forwarding pointers to the real stnicture pointed to, the value is stored into the byte 
specified by ppss in die location addressed by the forwarded base- pointer plus offset, nil is 
returned. This is the way to alter unboxed data within a structure without violating 
system storage conventions. 

%p- mask-field ppss pointer 

This is similar to %p-ldb, except that the selected byte is returned in its original position 
within die word instead of right-aligned. 

%p -mask- field-offset ppss base-pointer offset 

This is similar to %p-ldb- offset, except that the selected byte is returned in its original 
position within the word instead of right-aligned. 

%p-deposit-f ield value ppss pointer 

This is similar to %p-dpb, except that the selected byte is stored from the corresponding 
bits of value rather than the right-aligned bits. 

%p -deposit-field- offset value ppss base-pointer offset 

ITiis is similar to %p-dpb-offset, except that the selected byte is stored from the 
corresponding bits of value rather than the right-aligned bits. 

%p -pointer pointer 

Extracts the pointer field of the contents of the location addressed by pointer and returns 
it as a fixnum. 

%p -data- type pointer 

Extracts the data-type field of the contents of the location addressed by pointer and returns 
it as a fixnum. 

Ap-CuP-couS pointer 

Extracts the cdr-code field of the contents of the location addressed by pointer and returns 
it as a fixnum. 
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%p- store -pointer pointer value 

Clobbers tlie pointer field of the location addressed by pointer to value, and returns value. 

%p-store-data-type pointer value 

Clobbers the data-type field of the location addressed by pointer to value, and returns 
value. 

%p-store-cdr-code pointer value 

Clobbers the cdr-code field of the location addressed by pointer to value, and returns 
value. 

%s tack-frame-pointer 

Returns a locative pointer to its caller's stack frame. This ftinction is not defined in die 
interpreted Lisp environment; it only works in compiled code. Since it turns into a 
"misc" instmction, the "caller's stack frame" really means "the frame for the FHF that 
executed the %stack- frame -pointer instruction". 

14.1 1 Storage Layout Definitions 

The following special variables have values which define the most important attributes of the 
way Lisp data structures are laid out in storage. In addition to the variables documented here, 
there are many others that are more specialized. They are not documented in tiiis manual since 
they are in die system package rather than Uie global package. The variables whose names start 
with %% are byte specifiers, intended to be used with subprimitivcs such as %p-ldb. If you 
change the value of any of diese variables, you will probably bring the machine to a crashing 
halt. 

%%q- cdr-code Variable 

ITie field of a memory word diat contains Uie cdr-code. See section 5.4, page 72. 

%%q-flag-b1t Variable 

The field of a memory word diat contains die flag-bit. In most data structures diis bit is 
not used by die system and is available for die user. However, it may soon be 
reallocated to other purposes. 

%%q- data- type Variable 

The field of a memory word diat contains die data-type code. See page 201. 

%%q- pointer Variable 

The field of a memory word diat contains die pointer address, or immediate data. 

%%q-pointer-wi thin-page Variable 

The field of a memory word diat contains die part of die address diat lies widiin a single 
page. 
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. ^ Variable 

%%q-typed-pointer 

I'hc concatenation or uic %%q-uaici-ivpe anu /u/^m po!...v,. ncms. 

rt-no-intar Variable 

^^^"^l..." ^1.^.^^ ^.,^,..„ ,v-d tjv^^t rnntmns tjie tas ficMs, %%q-cdr-code and %%q-flag- 

bit. 

, ^ ^ . . ^ Variable 

%%q-an-but-pointer . 

The concatenation of all fields of a memory word except for %%q-pointer. 

, .. ^ J A^ Variable 

%%q-all-but-cdr-code 

The concatenation of all fields of a memory word except for %%q-cdr-code. 
. . ,* Variable 

'""'' 2 half *'''™*'' 

'""'"^°The wo halves of a memory word. These fields are only used in storing compiled code. 

Variable 
cdf^-"®^* Variable 

The values of these four variables are the numeric values that go in the cdr-code fie.d o. 
a memory word. See section 5.4, page 72 for the details of cdr-codmg. 

14.12 Function-Calling Subprimitivcs 

These subprimitivcs can be used (carefully!) to call a function with the ^^^"^^J tn^ZTd 
variable at run time. ITiey only work in compiled code and are not defined in the mterpreted 
Lisp environment. The preferred higher-level primitive is lexpr-funcall (page 27). 

%0Den-call -block function n-adi-pairs destination 

^ Smrts a call io fiinction. n-adi-pairs is the number of pairs of additional information 
words already %push'ed; normally this should be 0. destination is where to put die 
result; the useflil values are for the value to be ignored, 1 for the value to go onto tti^e 
stack, 3 for the value to be the last argument to the previous open call block, and 2 tor 
the value to be returned from this frame. 

%push value 

Pushes value onto the stack. Use this to push the arguments. 

%activate-open-call -block 

Causes the call to happen, 

^^""^ Pops the top value off of the stack and returns it as its value. Use this to recover the 
result from a call made by %open- call -block with a destination of 1. 



SRC:<L.MAN>FD-SUIi.TH)n\6 24-JAN-83 



Special-Binding Subprimitive 212 Lisp Machine Manual 



%assure-pdl-room n-words 

Call this before doing a sequence of %push's or %open-call-blocks that will add n- 
wonh to the current frame. Hiis subprimitive checks that the frame will not exceed the 
maximum legal frame size, which is 255 words including all overhead. This limit is 
dictated by tlie way stack frames are linked together. If tlie frame is going to exceed the 
legal limit, %assure-pdl-room will signal an error. 

14.13 Special-Binding Subprimitive 

bind locative value 

Binds the cell pointed to by locative to x, in the caller's environment. This function is 
not defined in the interpreted Lisp environment; it only works from compiled code. Since 
it turns into an instniction, the "caller's environment" really means "the binding block for 
the stack frame that executed the bind instruction". Ihe preferred higher-level primitives 
that turn into this are let (page 17), let-if (page 18), and progv (page 19). 
n his will be renamed to %bind in the future.] 

'! he binding is in effect for the scope of the innermost binding construct, such as prog or 
let— even one that binds no variables itself. 

14.14 The Paging System 

[Someday this may discuss how it works.] 

sys:%disk-sw1tches Variable 

This variable contains bits that control various disk usage features. 

Bit (the least significant bit) enables read-compares after disk read operations. This 
causes a considerable slowdown, so it is rarely used. 

Bit 1 enables read-compares after disk write operations. 

Bit 2 enables the multiple page swap-out feature. When this is enabled, as it is by 
default, each time a page is swapped out, up to 20 contiguous pages will also be written 
out to the disk if tiiey have been modified. This greatly improves swapping performance. 

Bit 3 controls the multiple page swap-in feature, which is also on by default. This feature 
causes pages to be swapped in in groups; each time a page is needed, several contiguous 
pages are swapped in in die same disk operation. ^Lhe number of pages swapped in can 
be specified for each area using si:set-swap-recommendations-of-area. 

si .-set-swap-recommendatlons-of-area area-number recommendation 

Specifics that pages of area area-number should be swapped in in groups of 
recommendation at a time. This recommendation is used only if the multiple page swap-in 
feature is enabled. 
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Generally, the more memory a machine has, the higher the swap recommendations should 
be to get optimum perfomiance. ITie recommendations are set automatically according to 
the memory si/.e when the machine is booted. 

si : set -all -swap -recommend at ions recommendation 

Specifies tlie swap-in recommendation of all areas at once, 

si:w ire-page address &optional ( wire-p t) 

If wire-p is t, the page containing address is wired-down; that is, it cannot be paged-out. 
If wire-p is nil, tlie page ceases to be wired-down. 

si:unwire-page address 

(si:unwire-page address) is the same as {si:wire-page address nil). 

sys:page-in-structure object 

Makes sure that the storage that represents object is in main memory. Any pages that 
have been swapped out to disk are read in, using as few disk operations as possible. 
Consecutive disk pages are transferred together, taking advantage of tlie full speed of the 
disk. If object is large, this will be much faster dian bringing the pages in one at a time 
on demand. The storage occupied by object is defined by the %find -structure -leader 
and %structure -total -size subprimitives. 

sys:page-in-array array &optional from to 

This is a version of sys:page-in-structure that can bring in a portion of an array, from 
and to are lists of subscripts; if they are shorter than tlic dimensionality of array, the 
remaining subscripts are assumed to be zero. 

sys:page-in-pixel -array array &optional from to 

Like sys:page- in -array except that the lists from and to, if present, are assumed to have 
their subscripts in the order horizontal, vertical, regardless of which of those two is 
actually die first axis of the array. See make -pixel -array, page 137. 

sys:page-in-words address n-words 

Any pages that have been swapped out to disk in die range of address space starting at 
address and continuing for n-words are read in with as few disk operations as possible. 

sys:page-in-area area-number 
sys: page- in- region region-number 

All swapped-out pages of the specified region or area are brought into main memory. 

sys: page-out-structure object 

sys: page-out-array array &optional from to 

sys :page-out-p1xel -array array &optional from to 

sys: page-out-words address n-words 

sys: page -out- area area-number 

sys: page-out-region region-number 

These are similar to the above, except that they take pages out of main memory rather 
than bringing them in. Actually, they only mark the pages as having priority for 
replacement by others. Use these operations when you are done with a large object, to 
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make the virtual memory system prefer reclaiming tliat object's memory over swapping 
something else out. 

sys:%chang8- page-status virtual-address swap-status access-status-and-meta-bits 

The page hash table entry for the page containing virtual- address is found and altered as 
specified, t is returned if it was found, nil if it was not (presumably tlie page is swapped 
out), swap-status and access-status-and-meta-bits can be nil if tliosc fields arc not to be 
changed. This doesn't make any error checks; you can really screw things up if you call 
it with the wrong arguments. 

sys :%compute-page-hash virtual-address 

This makes the hashing function for tlie page hash table available to the user. 

sys :%create-physical-page physical-address 

This is used when adjusting the size of real memory available to the machine. It adds an 
entry for the page frame at physical- address to the page hash table, with virtual address 
-1, swap suitus flushable, and map status 120 (read only). ITiis doesn't make error 
checks; you can really screw things up if you call it with the wrong arguments. 

sys :%d8lete-physical -page physical- address 

If there is a page in the page frame at physical- address, it is swapped out and its entry is 
deleted from the page hash table, making that page frame unavailable for swapping in of 
pages in the future. This doesn't make error checks; you can really screw tilings up if 
you call it with the wrong arguments. 

sys:%disk-restore high-16-bits low-16-bits 

Loads virtual memory from the partition named by the concatenation of the two 16-bit 
arguments, and starts executing it. The name refers to the default load (the one the 
machine loads when it is started up). This is the primitive used by disk -restore (see 
page 652). 

sys:%disk-save physical-mem-size high-16-bits low-16-bits 

Copies virtual memory into the partition named by the concatenation of the two 16-bit 
arguments (0 means the default), then restarts the world, as if it had just been restored. 
The physical-mem- size argument should come from %sys -com -memory -size in system - 
communication -area. This is die primitive used by disk -save (see page 654). 

si : set-memory-size nwords 

Specifies the size of physical memory in words. The Lisp machine determines the actual 
amount of physical memory when it is booted, but with this function you can tell it to 
use less memory than is actually present. This may be useful for comparing performance 
based on the amount of memory. 
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14.15 Closure Subprimitives 

These functions deal with things like what closures deal with: tlic distinction between internal 
and external value cells and control over how they work. 

sys :%b1nding-instanc8S list- of- symbols 

This is the primitive that could be used by closure. First, if any of tlie symbols in list- 
of-symboh has no external value cell, a new external value cell is created for it, with the 
contents of the internal value cell. Then a list of locatives, twice as long as list-of- 
symboh, is created and returned. The elements are grouped in pairs: pointers to the 
internal and external value cells, respectively, of each of the symbols, closure could have 
been defined by: 

(defun closure (variables function) 
(Xmake-pointer dtp-closure 

(cons function (sys:%binding-instances variables)))) 

sys:%using-binding-instances instance-list 

This function is the primitive operation that invocation of closures could use. It takes a 
list such as sys:%binding -instances returns, and for each pair of elements in the list, it 
"adds" a binding to tlic current stack frame, in the same m.anncr tliat tlie bind function 
(which should be called %bind) does. These bindings remain in effect until the frame 
returns or is unwound. 

sys:%using -binding -instances checks for redundant bindings and ignores them. (A 
binding is redundant if the symbol is already bound to the desired external value cell.) 
'ITiis check avoids excessive growth of the special pdl in some cases and is also made by 
the microcode which invokes closu.res, entities, and instances. 

Given a closure, closure -bindings extracts its list of binding instances, which you can 
then pass to sys:%using -binding -instances. 

sys:%internal-value-cen symbol 

Returns the contents of the internal value cell of symbol, dtp -one -q -forward pointers 
are considered invisible, as usual, but dtp-external-value-cell-pointers are not\ this 
ftinction can return a dtp-external-value-cell-pointer. Such pointers will be considered 
invisible as soon as they leave the "inside of the machine", meaning internal registers and 
the stack. 



14.16 Microcode Variables 

The following variables' values actually reside in the scratchpad memory of the processor. 
They are put there by dtp -one-q -forward invisible pointers. The values of these variables are 
used by the microcode. Many of these variables are highly internal and you shouldn't expect to 
understand them. 
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%microcode- version-number Variable 

I'his is the version number of tlie currently-loaded microcode, obtained from the version 
number of the micnxodc source file. 

sys :%number-of -micro-entries Variable 

Size of micro-code-entry-area and related areas, 

default-cons-area is documented on page 224. 

sys:number-cons-area Variable 

The area number of the area where bignums and flonums are consed. Normally this 
variable contains the value of sys:extra-pdl-area, which enables the "temporary storage" 
feature for num.bers, saving garbage collection overhead. 

current-stack-group and current-stack-group-resumer are documented on page 188. 

sys;%current-stack-group-state Variable 

The sg- state of the currently-running stack group. 

sys:%current-stack-group-caning-args-pointer Variable 

The argument list of tlie currently-running stack group. 

sys:%current-stack-group-caning-args-number Variable 

The number of arguments to the currently-running stack group. 

sys:%trap-^m1cP0-pc Variable 

ITie microcode address of the most recent error trap. 

sys:%init1al-fef Variable 

The function that is called when the machine starts up. Normally this is the definition of 
si:lisp-top-level. 

sys:%initial -stack-group Variable 

The stack group in which the machine starts up. 

sys :%error-han(ner-stack-group Variable 

The stack group that receives control when a microcode-detected error occurs. This stack 
group cleans up, signals the appropriate condition, or assigns a stack group to run the 
debugger on the erring stack group. 

sys:%schedu1er-stack-group Variable 

The stack group that receives control when a sequence break occurs. 

sys:%chaos-csr-address Variable 

A fixnum, the virtual address that maps to the Unibus location of the Chaosnet interface. 
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%mar-1ow Variable 

A fixnum, tlic inclusive lower bound oi the region oi virtual memory subject to the mAR 
feature (see section 27.13, page 599). 

%ni a p " h "i Q h Variable 

A fixnum, the inclusive upper bound of the region of virtual memory subject to tJie MAR 
feature (see section 27.13, page 599). 

sys:%inhibit-reacl-only Variable 

If non-nil, you can write into read-only areas. TTiis is used by fasload. 

self is documented on page 338. 

inhibit-scheduling-flag is documented on page 540. 

inhibit-scavenging-flag Variable 

If non-nil, the scavenger is turned off. The scavenger is the quasi-asynchronous portion of 
the garbage collector, which normally runs during consing operations, 

sys:scavenger-ws-enable Variable 

If this is nil, scavenging can compete for all of the physical memory of the machine. 
Otherwise, it should be a fixnum, which specifies how much physical memory the 
scavenger can use: page numbers as high as this number or higher are not available to it. 

sys:%region-cons-alapm Variable 

Incremented whenever a new region is allocated. 

sys:%pag8-cons-alarm Variable 

Increments whenever a new page is allocated. 

sys:%gc-f lip-ready Variable 

t while the scavenger is running, nil when there are no pointers to oldspace. 

sys:%gc-gen8ration-number Variable 

A fixnum which is incremented whenever the garbage collector flips, converting one or 
more regions from newspace to oldspace. If this number has changed, the %pointer of 
an object may have changed. 

sys:%d1sk- run- light Variable 

A fixnum, die virtual address of the TV buffer location of the run-light which lights up 
when the disk is active. This plus 2 is the address of the run-light for the processor. 
This minus 2 is the address of the run-light for the garbage collector. 

sys:%loaded-band Variable 

A fixnum, the high 24 bits of the name of the disk partition from which virtual memory 
was booted. Used to create the greeting message. 
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sys :%disk-blocks-per-track Variable 

sys:%disk-blocks-per-cylinder Variable 

Configuration of the disk being used for paging. Don't change these! 

sys:%disk-switches is documented on page 212. 

sys:%qlaryh Variable 

niis is the last array to be called as a function, remembered for tlie sake of the function 
store. 

sys:%qlaryl Variable 

This is tlie index used tlie last time an array was called as a function, remembered for 
the sake of the function store. 

%mc- code-ex it- vector Variable 

I'his is a vector of pointers that microcompiled code uses to refer to quoted constants. 

sys; currently-prepared-sheet Variable 

Used for communication between tlie window system and the microcoded graphics 
primitives. 

sys:alphabetic-case-affects-string -comparison is documented on page 144. 

sys:tail- recursion -flag is documented on page 33. 

zunderflow/ is documented on page 104. 

The next four have to do with implementing the metering system described in section 32.2, page 
637. 

sys :%meter-globa1 -enable Variable 

t if the metering system is turned on for all stack-groups. 

sys :%meter-buf fer-pointer Variable 

A temporary buffer used by the metering system. 

sys:%meter-d1sk-address Variable 

Where the metering system writes its next block of results on the disk. 

sys:%meter-d1sk-count Variable 

The number of disk blocks remaining for recording of metering information. 

sys: lexical -environment Variable 

This is the list of previous stack frames used by lexical -closure. 
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sys:amem-evcp- vector Variable 

This is a vector of shadow locations for all these microcode variables, used in 
implementing closure-binding of them. Vac micrix:ode does not check for tlic presence of 
external value cell pointers in the microcode locations that these variables correspond to; 
therefore, v^hen a closure would otherwise try to store an external value cell pointer into 
one of Lhem, it goes in this vector instead. 

background -cons -area is documented on page 224. 

sys:self-mapping -table is documented on page 356. 

sys:%gc-switch8S Variable 

What is this used for? 

sys:a-memory- location -names Variable 

A list of all of the above symbols (and any others added after this documentation was 
written). 

14.17 Meters 

read-meter name 

Returns the contents of the microcode meter named name, which can be a fixnum or a 
bignum. name must be one of Uie symbols listed below. 

write -meter name value 

Writes value, a fixnum or a bignum, into the microcode meter named name, name must 
be one of the symbols listed below. 

The microcode meters are as follows: 

sys :%count-chaos-transmit-aborts Meter 

7'he number of times transmission on the Chaosnet was aborted, either by a collision or 
because the receiver was busy. 

sys:%count-cons-work Meter 
sys:%count-scavenger-worlc Meter 

Internal state of the garbage collection algorithm. 

sys :%tv- clock- rate Meter 

ITie number of TV frames per clock sequence break. The default value is 67., which 
causes clock sequence breaks to happen about once per second. 

sys :%count-f1rst-level -map-reloads Meter 

The number of times the first-level virtual-memory map was invalid and had to be 
reloaded from the page hash table. 
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sys :%count-second-level-map-reloads Meter 

The number of times the second-level virtual-memory map was invalid and had to be 
reloaded from the page hash table. 

sys:%count-meta-bits-map-r8loads Meter 

The number of times tlie virtual address map was reloaded to contain only "meta bits", 
not an actual physical address. 

sys :%count-pd1 -buffer-read-faults Meter 

rhe number of read references to tlie pdl buffer that were virtual memory references that 
trapped. 

sys:%count-pdl-buffer-write-faults Meter 

The number of write references to the pdl buffer that were virtual memory references that 
trapped. 

sys:%count-pdl-buffer-memopy-fau1ts Meter 

The number of virtual memory references tliat trapped in case they should have gone to 
the pdl buffer, but turned out to be real memorj' references after all (and therefore were 
needlessly slowed down). 

sys :%count-disk-page-reads Meter 

The number of pages read from the disk. 

sys :%count-disk-page-wr1tes Meter 

The number of pages written to the disk. 

sys:%count-fresh-pages Meter 

The number of fresh (newly-consed) pages created in core, which would have otherwise 
been read from the disk. 

sys :%count-disk-page-read-operations Meter 

The number of paging read operations; this can be smaller than the number of disk pages 
read when more than one page at a time is read. 

sys :%count-disk-page-write-operat1ons Meter 

The number of paging write operations; this can be smaller than the number of disk 
pages written when more than one page at a time is written, 

sys:%count-disk-prepages-used Meter 

The number of times a page was used after being read in before it was needed. 

sys :%count-disk-prepages-not-used Meter 

The number of times a page was read in before it was needed, but got evicted before it 
was ever used. 
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sys:%count-disk-page-write-waits Meter 

The number of limes the machine waited for a page to finish being written out in order 
to evict the page. 

sys:%count-disk-pag8-vfrit8-biJsys Meier 

The number of times the machine waited for a page to finish being written out in order 
to do something else with the disk. 

sys:%disk-wait-tim8 Meter 

The time spent waiting for the disk, in microseconds. This can be used to distinguish 
paging time from running time when measuring and optimizing the' performance of 
programs. 

sys:%count-disk-errors Meter 

The number of recoverable disk errors. 

sys:%count-d1sk-recal ibrates Meter 

The number of times the disk seek mechanism was recalibrated, usually as part of error 
recovery. 

sys :%count-d1sk-ecc-copr8Cted-errors Meter 

The number of disk errors that were corrected through the error correcting code. 

sys:%count-disk-read-compare-differences Meter 

The number of times a read compare was done, no disk error occurred, but the data on 
disk did not match the data in memory. 

sys:%count-disk-read-compare-rereads Meter 

The number of times a disk read was done over because after the read a read compare 
was done and did not succeed (either it got an error or the data on disk did not match 
the data in memory). 

sys:%count-d1sk-read-compare-rewrites Meter 

The number of times a disk write was done over because after the write a read compare 
was done and did not succeed (either it got an error or the data on disk did not match 
the data in memory). 

sys :%disk-epror- log-pointer Meter 

Address of the next entry to be written in the disk error log. The function si:print-disk- 
error-log (see page 643) prints this log. 



sys:%count-ag6d-pages Meter 

TT-no niii-nKnr r>f timA>< 

was being referenced. 
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sys :%count-age-f lushed-pages Meter 

The number of times the page ager saw that a page still had an age trap and hence made 
it "flushablc", a candidate for eviction from main memory. 

sys:%aging-depth Meter 

A number fr(ym to 3 tliat controls how long a page must remain unreferenced before it 
becomes a candidate for eviction from main memory. 

sys :%count-f indcore-steps Meter 

I he number of pages inspected by the page replacement algorithm. 

sys :%count-f indcore-emergencies Meter 

The number of times no evictable page was found and extra aging had to be done. 

sys :a-memory-counter-block-names Variable 

A list of all of the above symbols (and any others added after this documentation was 
written). 
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